BluetoothCentralManager PRO#

The BluetoothCentralManager namespace provides core functionality for managing Bluetooth Low Energy (BLE) operations as a central device. It supports scanning, connecting, disconnecting, and retrieving known or connected peripherals. This API is ideal for building custom Bluetooth workflows, interacting with smart devices, wearables, and IoT peripherals.

Properties#

isScanning: Promise<boolean>#

Returns whether the central manager is currently scanning for peripherals.

• Type: Promise<boolean>

• Example:

  1const scanning = await BluetoothCentralManager.isScanning
  2console.log(scanning ? "Scanning..." : "Not scanning")

Methods#

startScan(onDiscoverPeripheral, options?): Promise<void>#

Starts scanning for BLE peripherals. The scan continues until you call stopScan(). The callback will be triggered every time a peripheral is discovered.

Parameters#

• onDiscoverPeripheral: (peripheral, advertisementData, rssi) => void

  • Callback triggered on discovery.

  • Arguments:

    • peripheral: A BluetoothPeripheral object
    • advertisementData: A BluetoothAdvertisementData object
    • rssi: Signal strength in dBm

• options?: { services?: string[]; allowDuplicates?: boolean; solicitedServiceUUIDs?: string[] }

  • services: An array of UUID strings to filter devices by services
  • allowDuplicates: If true, reports duplicates; if false (default), filters out repeated discoveries
  • solicitedServiceUUIDs: An array of UUID strings to filter devices by solicited services

BluetoothAdvertisementData#

When using BluetoothCentralManager.startScan() to scan for Bluetooth peripherals, each discovered device includes an advertisementData object. This object contains key metadata extracted from the peripheral's BLE advertisement packets. It can help identify, filter, or categorize devices before establishing a connection.

Type Definition#

1type BluetoothAdvertisementData = {
2  localName?: string
3  txPowerLevel?: number
4  manufacturerData?: Data
5  serviceData?: Record<string, Data>
6  serviceUUIDs?: string[]
7  overflowServiceUUIDs?: string[]
8  isConnectable?: boolean
9  solicitedServiceUUIDs?: string[]
10}

Field Descriptions#

Common Use Cases#

• Filtering devices by localName, serviceUUIDs, or isConnectable
• Identifying vendor-specific devices using manufacturerData
• Estimating distance using txPowerLevel + RSSI
• Understanding device intentions via solicitedServiceUUIDs

Notes#

• All fields are optional; some peripherals may omit certain fields.
• manufacturerData and serviceData are raw Data objects and must be parsed using manufacturer-specific formats.
• serviceUUIDs represent only advertised services. To get the full list of available services, call peripheral.discoverServices() after connecting.

Returns#

• Promise<void>

Example#

1await BluetoothCentralManager.startScan((peripheral, adv, rssi) => {
2  console.log(`Discovered ${peripheral.name} with RSSI ${rssi}`)
3}, {
4  services: ["180D"], // Filter for Heart Rate Service
5  allowDuplicates: false
6})

stopScan(): Promise<void>#

Stops an ongoing scan.

Returns#

• Promise<void>

Example#

1await BluetoothCentralManager.stopScan()
2console.log("Scan stopped")

retrievePeripherals(ids: string[]): Promise<BluetoothPeripheral[]>#

Retrieves known peripherals by their identifiers.

Parameters#

• ids: An array of peripheral UUID strings

Returns#

• Promise<BluetoothPeripheral[]>

Example#

1const known = await BluetoothCentralManager.retrievePeripherals(["A1-B2-C3-D4"])

retrieveConnectedPeripherals(serviceUUIDs: string[]): Promise<BluetoothPeripheral[]>#

Retrieves currently connected peripherals that provide at least one of the specified services.

Parameters#

• serviceUUIDs: An array of service UUID strings

Returns#

• Promise<BluetoothPeripheral[]>

Example#

1const connected = await BluetoothCentralManager.retrieveConnectedPeripherals(["180F"])
2console.log(`Found ${connected.length} connected devices with Battery Service`)

connect(peripheral, options?): Promise<void>#

Establishes a connection to the specified peripheral.

Parameters#

• peripheral: A BluetoothPeripheral object to connect to

• options?:

  • startDelay?: number – Delay in seconds before connecting
  • enableTransportBridging?: boolean – Enables transport bridging (advanced)
  • requiresANCS?: boolean – Whether Apple Notification Center Service is required
  • enableAutoReconnect?: boolean – Whether to auto-reconnect if disconnected
  • notifyOnConnection?: boolean - Whether to notify when the connection is established
  • notifyOnDisconnection?: boolean - Whether to notify when the connection is disconnected
  • notifyOnNotification?: boolean - Whether to notify when a notification is received

Returns#

• Promise<void>

Example#

1await BluetoothCentralManager.connect(peripheral, {
2  startDelay: 100,
3  enableAutoReconnect: true
4})
5console.log("Connected")

disconnect(peripheral): Promise<void>#

Disconnects from the specified peripheral. This is a non-blocking operation.

Parameters#

• peripheral: A BluetoothPeripheral object

Returns#

• Promise<void>

Notes#

• Physical disconnection is not guaranteed if other apps are connected to the same peripheral.
• From the app's perspective, the device is considered disconnected and onDisconnected will be triggered.

Example#

1await BluetoothCentralManager.disconnect(peripheral)
2console.log("Disconnected")

Workflow Example#

1await BluetoothCentralManager.startScan((peripheral) => {
2  BluetoothCentralManager.stopScan()
3  BluetoothCentralManager.connect(peripheral)
4    .then(() => peripheral.discoverServices())
5    .then(() => console.log("Services discovered"))
6})

Best Practices#

• Always call stopScan() when scanning is no longer needed to save battery and reduce system load.
• Make sure Bluetooth permissions are granted before using these APIs.
• After connecting to a peripheral, call discoverServices() followed by discoverCharacteristics() before reading or writing data.